{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Skforecast migration guide\n",
    "\n",
    "This document contains a set of instructions on how to update your code to work with the latest version of Skforecast."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Version 0.19.0\n",
    "\n",
    "### Parameter regressor renamed to estimator\n",
    "\n",
    "In Skforecast 0.19.0, the parameter and attribute `regressor` has been deprecated in favor of `estimator` in all Forecasters and will be removed in future releases to align with scikit-learn terminology."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table>\n",
    "\n",
    "<tr>\n",
    "<td style=\"text-align: center;\"><strong>skforecast &lt; 0.19</strong></td>\n",
    "<td style=\"text-align: center;\"><strong>skforecast &ge; 0.19</strong></td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "forecaster = ForecasterRecursive(\n",
    "                 regressor = LGBMRegressor(),\n",
    "                 lags      = 15\n",
    "             )\n",
    "\n",
    "print(forecaster.regressor)\n",
    "```\n",
    "\n",
    "</td>\n",
    "\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "forecaster = ForecasterRecursive(\n",
    "                 estimator = LGBMRegressor(),\n",
    "                 lags      = 15\n",
    "             )\n",
    "\n",
    "print(forecaster.estimator)\n",
    "```\n",
    "\n",
    "</td>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Changes in the import of the library\n",
    "\n",
    "Skforecast Sarimax-related modules have been moved to a new submodule named `stats`. Also the `ForecasterSarimax` class has been renamed to `ForecasterStats`.\n",
    "\n",
    "The new import of the Sarimax-related modules is as follows:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table>\n",
    "\n",
    "<tr>\n",
    "<td style=\"text-align: center;\"><strong>skforecast &lt; 0.19</strong></td>\n",
    "<td style=\"text-align: center;\"><strong>skforecast &ge; 0.19</strong></td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.sarimax import Sarimax\n",
    "from skforecast.recursive import ForecasterSarimax\n",
    "from model_selection import backtesting_sarimax\n",
    "from model_selection import grid_search_sarimax\n",
    "from model_selection import random_search_sarimax\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.stats import Sarimax\n",
    "from skforecast.recursive import ForecasterStats\n",
    "from model_selection import backtesting_stats\n",
    "from model_selection import grid_search_stats\n",
    "from model_selection import random_search_stats\n",
    "```\n",
    "</td>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Version 0.14.0\n",
    "\n",
    "### Changes in the import of the library\n",
    "\n",
    "Skforecast modules have been reorganized and renamed to make it more intuitive. The new import of the library is as follows:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "vscode": {
     "languageId": "html"
    }
   },
   "source": [
    "<table>\n",
    "\n",
    "<tr>\n",
    "<td style=\"text-align: center;\"><strong>skforecast &lt; 0.14</strong></td>\n",
    "<td style=\"text-align: center;\"><strong>skforecast &ge; 0.14</strong></td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.ForecasterAutoreg import ForecasterAutoreg\n",
    "from skforecast.ForecasterAutoregMultiSeries import ForecasterAutoregMultiSeries\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.recursive import ForecasterRecursive\n",
    "from skforecast.recursive import ForecasterRecursiveMultiSeries\n",
    "```\n",
    "</td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.ForecasterAutoregCustom import ForecasterAutoregCustom\n",
    "from skforecast.ForecasterAutoregMultiSeriesCustom import ForecasterAutoregMultiSeriesCustom\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "Not exist any more, use [`ForecasterRecursive`](../api/forecasterrecursive.html) or [`ForecasterRecursiveMultiSeries`](../api/forecasterrecursivemultiseries.html) instead and the `window_features` to include any [window or custom feature](../user_guides/window-features-and-custom-features.html).\n",
    "\n",
    "</td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.ForecasterAutoregDirect import ForecasterAutoregDirect\n",
    "from skforecast.ForecasterAutoregMultiVariate import ForecasterAutoregMultiVariate\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.direct import ForecasterDirect\n",
    "from skforecast.direct import ForecasterDirectMultiVariate\n",
    "```\n",
    "</td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from model_selection import backtesting_forecaster\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from model_selection import TimeSeriesFold\n",
    "from model_selection import backtesting_forecaster\n",
    "```\n",
    "</td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from model_selection_multiseries import backtesting_forecaster_multiseries\n",
    "from model_selection_multiseries import grid_search_forecaster_multiseries\n",
    "from model_selection_multiseries import random_search_forecaster_multiseries\n",
    "from model_selection_multiseries import bayesian_search_forecaster_multiseries\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from model_selection import backtesting_forecaster_multiseries\n",
    "from model_selection import grid_search_forecaster_multiseries\n",
    "from model_selection import random_search_forecaster_multiseries\n",
    "from model_selection import bayesian_search_forecaster_multiseries\n",
    "```\n",
    "</td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from model_selection import select_features\n",
    "from model_selection_multiseries import select_features_multiseries\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from feature_selection import select_features\n",
    "from feature_selection import select_features_multiseries\n",
    "```\n",
    "</td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.Sarimax import Sarimax\n",
    "from model_selection_sarimax import backtesting_sarimax\n",
    "from model_selection_sarimax import grid_search_sarimax\n",
    "from model_selection_sarimax import random_search_sarimax\n",
    "```\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "from skforecast.sarimax import Sarimax\n",
    "from model_selection import backtesting_sarimax\n",
    "from model_selection import grid_search_sarimax\n",
    "from model_selection import random_search_sarimax\n",
    "```\n",
    "</td>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Custom features (window features)\n",
    "\n",
    "Forecasters `ForecasterAutoregCustom` and `ForecasterAutoregMultiSeriesCustom` have been removed. Now, you can use `ForecasterRecursive` and `ForecasterDirect` and include custom features using the `window_features` parameter. To learn more about how to include custom features, check the [documentation](../user_guides/window-features-and-custom-features.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table>\n",
    "\n",
    "<tr>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &lt; 0.14</strong></td>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &ge; 0.14</strong></td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "from skforecast.ForecasterAutoregCustom import ForecasterAutoregCustom\n",
    "import numpy as np\n",
    "\n",
    "def create_predictors(y):\n",
    "    \"\"\"\n",
    "    Create first 10 lags of a time series.\n",
    "    Calculate moving average with window 20.\n",
    "    Calculate the moving standard deviation with window 20.\n",
    "    Calculate moving minimum and maximum with window 20.\n",
    "    \"\"\"\n",
    "    lags = y[-1:-11:-1]\n",
    "    mean = np.mean(y[-20:])\n",
    "    std = np.std(y[-20:])\n",
    "    min_val = np.min(y[-20:])\n",
    "    max_val = np.max(y[-20:])\n",
    "\n",
    "    predictors = np.hstack([lags, mean, std, min_val, max_val])\n",
    "\n",
    "    return predictors\n",
    "\n",
    "feature_names = [f\"lag {i}\" for i in range(1, 11)] + [\n",
    "    \"moving_avg_20\",\n",
    "    \"moving_std_20\",\n",
    "    \"moving_min_20\",\n",
    "    \"moving_max_20\",\n",
    "]\n",
    "\n",
    "forecaster = ForecasterAutoregCustom(\n",
    "    estimator       = LGBMRegressor(random_state=123, verbose=-1),\n",
    "    fun_predictors  = create_predictors,\n",
    "    name_predictors = feature_names,\n",
    "    window_size     = 20\n",
    ")\n",
    "```\n",
    "\n",
    "</td>\n",
    "\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "from skforecast.recursive import ForecasterRecursive\n",
    "from skforecast.preprocessing import RollingFeatures\n",
    "\n",
    "rolling = RollingFeatures(\n",
    "    ststs        = ['mean', 'std', 'min', 'max'],\n",
    "    window_sizes = [20, 20, 20, 20]\n",
    ")\n",
    "\n",
    "forecaster = ForecasterRecursive(\n",
    "    estimator       = LGBMRegressor(random_state=123, verbose=-1),\n",
    "    lags            = 10,\n",
    "    window_features = rolling\n",
    ")\n",
    "```\n",
    "</td>\n",
    "\n",
    "</tr>\n",
    "\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Changes the backtesting\n",
    "\n",
    "The arguments `initial_train_size`, `window_size`, `differentiation`, `refit`, `fixed_train_size`, `gap`, `skip_folds`, `allow_incomplete_fold`, `return_all_indexes`, and `verbose` are no longer defined in the `backtesting_forecaster` function. Instead, an instance of `TimeSeriesFolds` should be created, and these arguments should be specified in the class constructor. This change not only allows the same folds to be reused across different methods, but also provides the ability to extract fold indexes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table>\n",
    "\n",
    "<tr>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &lt; 0.14</strong></td>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &ge; 0.14</strong></td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "from skforecast.model_selection import (\n",
    "    backtesting_forecaster\n",
    ")\n",
    "\n",
    "backtesting_forecaster(\n",
    "    forecaster            = forecaster,\n",
    "    y                     = y,\n",
    "    steps                 = 10,\n",
    "    initial_train_size    = 100,\n",
    "    metric                = 'mean_absolute_error',\n",
    "    fixed_train_size      = True,\n",
    "    gap                   = 0,\n",
    "    skip_folds            = None,\n",
    "    allow_incomplete_fold = True,\n",
    "    refit                 = False,\n",
    "    n_jobs                = 'auto',\n",
    "    verbose               = False,\n",
    "    show_progress         = True\n",
    ")\n",
    "```\n",
    "\n",
    "</td>\n",
    "\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "from skforecast.model_selection import (\n",
    "    TimeSeriesFold,\n",
    "    backtesting_forecaster\n",
    ")\n",
    "\n",
    "cv = TimeSeriesFold(\n",
    "    steps                 = 10,\n",
    "    initial_train_size    = 100,\n",
    "    fixed_train_size      = True,\n",
    "    gap                   = 0,\n",
    "    skip_folds            = None,\n",
    "    allow_incomplete_fold = True,\n",
    "    refit                 = False\n",
    ")\n",
    "\n",
    "backtesting_forecaster(\n",
    "    forecaster            = forecaster,\n",
    "    y                     = y,\n",
    "    cv                    = cv,\n",
    "    metric                = 'mean_absolute_error',\n",
    "    n_jobs                = 'auto',\n",
    "    verbose               = False,\n",
    "    show_progress         = True\n",
    ")\n",
    "```\n",
    "</td>\n",
    "\n",
    "</tr>\n",
    "\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Changes in hyperparameters search\n",
    "\n",
    "The arguments `initial_train_size`, `window_size`, `differentiation`, `refit`, `fixed_train_size`, `gap`, `skip_folds`, `allow_incomplete_fold`, `return_all_indexes`, and `verbose` are no longer defined in the `grid_search_forecaster`, `random_search_forecaster` and `bayesian_search_forecaster` functions. Instead, an instance of `TimeSeriesFolds` or `OneStepAheadFold` should be created, and these arguments should be specified in the class constructor."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table>\n",
    "\n",
    "<tr>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &lt; 0.14</strong></td>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &ge; 0.14</strong></td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "from skforecast.model_selection import (\n",
    "    grid_search_forecaster\n",
    ")\n",
    "\n",
    "grid_search_forecaster(\n",
    "    forecaster            = forecaster,\n",
    "    y                     = data,\n",
    "    param_grid            = param_grid,\n",
    "    lags_grid             = lags_grid,\n",
    "    steps                 = 10,\n",
    "    refit                 = False,\n",
    "    metric                = 'mean_squared_error',\n",
    "    initial_train_size    = 100,\n",
    "    fixed_train_size      = False,\n",
    "    allow_incomplete_fold = True,\n",
    "    return_best           = True,\n",
    "    n_jobs                = 'auto',\n",
    "    verbose               = False,\n",
    "    show_progress         = True\n",
    ")\n",
    "```\n",
    "\n",
    "</td>\n",
    "\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "from skforecast.model_selection import (\n",
    "    grid_search_forecaster,\n",
    "    TimeSeriesFold\n",
    ")\n",
    "\n",
    "cv = TimeSeriesFold(\n",
    "    steps                 = 10,\n",
    "    initial_train_size    = 100,\n",
    "    fixed_train_size      = False,\n",
    "    gap                   = 0,\n",
    "    skip_folds            = None,\n",
    "    allow_incomplete_fold = True,\n",
    "    refit                 = False\n",
    ")\n",
    "\n",
    "grid_search_forecaster(\n",
    "    forecaster         = forecaster,\n",
    "    y                  = data,\n",
    "    param_grid         = param_grid,\n",
    "    lags_grid          = lags_grid,\n",
    "    cv                 = cv,\n",
    "    metric             = 'mean_squared_error',\n",
    "    return_best        = True,\n",
    "    n_jobs             = 'auto',\n",
    "    verbose            = False,\n",
    "    show_progress      = True\n",
    ")\n",
    "```\n",
    "</td>\n",
    "\n",
    "</tr>\n",
    "\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Overall structure of the repository"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table>\n",
    "\n",
    "<tr>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &lt; 0.14</strong></td>\n",
    "    <td style=\"text-align: center;\"><strong>skforecast &ge; 0.14</strong></td>\n",
    "</tr>\n",
    "\n",
    "<tr>\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "|-- skforecast\n",
    "    |-- ForecasterAutoreg\n",
    "        |-- ForecasterAutoreg.py              -> ForecasterAutoreg \n",
    "    |-- ForecasterAutoregCustom.py\n",
    "        |-- ForecasterAutoregCustom.py        -> ForecasterAutoregCustom\n",
    "    |-- ForecasterAutoregDirect\n",
    "        |-- ForecasterAutoregDirect.py        -> ForecasterAutoregDirect\n",
    "    |-- ForecasterAutoregMultiSeries\n",
    "        |-- ForecasterAutoregMultiSeries.py   -> ForecasterAutoregMultiSeries\n",
    "    |-- ForecasterAutoregMultiVariate\n",
    "        |-- ForecasterAutoregMultiVariate.py  -> ForecasterAutoregMultiVariate\n",
    "    |-- ForecasterRnn\n",
    "        |-- ForecasterRnn.py                  -> ForecasterRnn\n",
    "    |-- ForecsaterBase\n",
    "        |-- ForecasterBase.py                 -> ForecasterBase\n",
    "    |-- ForecasterSarimax\n",
    "        |-- ForecasterSarimax.py              -> ForecasterSarimax\n",
    "    |-- Sarimax\n",
    "        |-- Sarimax.py                        -> Sarimax\n",
    "```\n",
    "\n",
    "</td>\n",
    "\n",
    "<td style=\"vertical-align: top;\">\n",
    "\n",
    "```python\n",
    "|-- skforecast\n",
    "    |-- recursive\n",
    "        |-- _forecaster_recursive.py              -> ForecasterRecursive\n",
    "        |-- _forecaster_recursive_multiseries.py  -> ForecasterRecursiveMultiSeries\n",
    "        |-- _forecaster_sarimax.py                -> ForecasterSarimax\n",
    "        |-- _forecaster_equivalent_date.py        -> ForecasterEquivalentDate\n",
    "    |-- direct\n",
    "        |-- _forecaster_direct.py                 -> ForecasterDirect\n",
    "        |-- _forecaster_direct_multivariate.py    -> ForecasterDirectMultiVariate\n",
    "    |-- deep_learning\n",
    "        |-- _forecaster_rnn.py                    -> ForecasterRnn\n",
    "    |-- base\n",
    "        |-- _forecaster_base.py                   -> ForecasterBase\n",
    "    |-- sarimax\n",
    "        |-- _sarimax.py                           -> Sarimax\n",
    "```\n",
    "</td>\n",
    "\n",
    "</tr>\n",
    "\n",
    "</table>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "skforecast_15_p12",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
